Overview

Adds full asyncio/coroutine support to Cachier, enabling the existing @cachier decorator to transparently cache both synchronous and asynchronous functions without requiring separate decorators or code changes.

Implementation

Core Changes (src/cachier/core.py):

• Added async detection via inspect.iscoroutinefunction()
• Created parallel async execution path: _call_async(), _calc_entry_async(), _function_thread_async()
• Decorator automatically returns async wrapper for coroutines, sync wrapper for regular functions
• Removed blocking wait_on_entry_calc() in async path - concurrent calls execute in parallel to avoid event loop blocking
• Storage layer (cores) remains synchronous - no changes needed
• Simplified async stale entry handling by removing unreachable code path

Testing (tests/test_async_core.py):

• 30 comprehensive tests (consolidated, no duplicates) covering async scenarios:
  • Basic caching with memory and pickle backends
  • stale_after, next_time, max_age parameters
  • Concurrent async calls and cache behavior
  • Class methods and different argument types
  • allow_none, ignore_cache, overwrite_cache parameters
  • Verbose mode and debug output
  • Global caching enable/disable control
  • Cleanup stale entries functionality
  • Exception handling in background tasks
  • Entry size limit exceeded
  • Edge cases: negative max_age, entry processing, stale entry handling
• Backward compatibility validation (sync functions still work)
• Test docstrings refer to behavior/case rather than line numbers
• Clean test structure with class-level pytest marks where applicable

Examples (examples/async_example.py):

• Practical demonstrations of async caching
• HTTP request caching example
• Stale-after and concurrent request scenarios

Features

All existing Cachier features work with async functions:

• ✅ All backends: pickle, memory, MongoDB, Redis, SQL
• ✅ Stale cache handling (stale_after, next_time)
• ✅ Max age parameter for cache freshness
• ✅ Cache control (ignore_cache, overwrite_cache)
• ✅ Verbose mode for debugging
• ✅ Global caching enable/disable
• ✅ Automatic cleanup of stale entries
• ✅ None value caching control (allow_none)
• ✅ Exception handling in background tasks
• ✅ Entry size limit handling

Usage

from cachier import cachier
import asyncio
from datetime import timedelta

@cachier(backend="memory", stale_after=timedelta(hours=1))
async def fetch_user(user_id: int) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com/users/{user_id}")
        return response.json()

# First call: makes HTTP request, caches result
# Second call: returns cached result instantly
user = await fetch_user(42)

Design Notes

• No Breaking Changes: All existing sync functionality unchanged
• Async Efficiency: Concurrent async calls with identical arguments execute in parallel initially (no blocking wait), subsequent calls use cache
• Event Loop Safety: wait_for_calc_timeout not honored for async functions to avoid blocking the event loop
• Simple Implementation: Storage cores remain synchronous (just I/O operations), keeping implementation clean and maintainable
• Code Simplification: Removed unreachable edge case code for cleaner async path
• Clean Tests: Class-level pytest marks reduce duplication

Testing Results

• ✅ All 30 async tests passing
• ✅ All existing sync tests passing (backward compatibility verified)
• ✅ Linting: 0 errors (ruff with 120 char line length)
• ✅ Type checking: passing (mypy)
• ✅ Security: 0 alerts (CodeQL)
• ✅ Complete code coverage for all reachable async paths
• ✅ No duplicate tests - consolidated and optimized test suite
• ✅ No unreachable code in async paths
• ✅ Clean test structure with minimal redundancy

The implementation is production-ready with comprehensive, non-redundant test coverage for all async code paths!

• Fixes Support for coroutines (asyncio) #27

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.